home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat5 / dplace.z / dplace
Encoding:
Text File  |  2002-10-03  |  15.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDPPPPLLLLAAAACCCCEEEE((((5555))))                                                            DDDDPPPPLLLLAAAACCCCEEEE((((5555))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddppppllllaaaacccceeee - NUMA placement specification
  10.  
  11.  
  12. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  13.      Placement specifications are described in placement files or invoked from
  14.      the command language library.  A valid placement specification contains
  15.      descriptions for memory and thread placement. Memory topologies as well
  16.      as affinities to devices may also be specified. Shared virtual address
  17.      ranges can be mapped to a specified memory. Page size and page migration
  18.      thresholds can also be controlled.
  19.  
  20.  
  21. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  22.      An example placement file describing two memories and two threads might
  23.      look like:
  24.  
  25.  
  26.      #### ppppllllaaaacccceeeemmmmeeeennnntttt ssssppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn ffffiiiilllleeee
  27.  
  28.      #### sssseeeetttt uuuupppp 2222 mmmmeeeemmmmoooorrrriiiieeeessss wwwwhhhhiiiicccchhhh aaaarrrreeee cccclllloooosssseeee
  29.      mmmmeeeemmmmoooorrrriiiieeeessss 2222 iiiinnnn ttttooooppppoooollllooooggggyyyy ccccuuuubbbbeeee
  30.  
  31.      #### sssseeeetttt uuuupppp 2222 tttthhhhrrrreeeeaaaaddddssss
  32.      tttthhhhrrrreeeeaaaaddddssss 2222
  33.  
  34.      #### rrrruuuunnnn tttthhhheeee ffffiiiirrrrsssstttt tttthhhhrrrreeeeaaaadddd oooonnnn tttthhhheeee 2222nnnndddd mmmmeeeemmmmoooorrrryyyy
  35.      rrrruuuunnnn tttthhhhrrrreeeeaaaadddd 0000 oooonnnn mmmmeeeemmmmoooorrrryyyy 1111
  36.  
  37.      #### rrrruuuunnnn tttthhhheeee 2222nnnndddd tttthhhhrrrreeeeaaaadddd oooonnnn tttthhhheeee ffffiiiirrrrsssstttt mmmmeeeemmmmoooorrrryyyy
  38.      rrrruuuunnnn tttthhhhrrrreeeeaaaadddd 1111 oooonnnn mmmmeeeemmmmoooorrrryyyy 0000
  39.  
  40.  
  41.  
  42.      This specification, when used for initial placement, would request 2
  43.      nearby memories from the operating system. At creation, the threads are
  44.      requested to run on an available cpu which is local to the specified
  45.      memory. As data and stack space is touched or faulted in, physical memory
  46.      is allocated from the memory which is local to the thread which initiated
  47.      the fault.
  48.  
  49. SSSSUUUUMMMMMMMMAAAARRRRYYYY
  50.      Commands are newline terminated.
  51.  
  52.      Characters following the comment delimiter '#' are ignored.
  53.  
  54.      Tokens are separated by optional whitespace which is ignored.
  55.  
  56.      Line continuation is a \, and must occur between tokens.
  57.  
  58.      In what follows  _k,_l,_m,_n,_t_0,_t_1,_d_t,_m_0,_m_1 and _d_m are arithmetic expressions
  59.      that can contain environment variables preceded by a '$'.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDPPPPLLLLAAAACCCCEEEE((((5555))))                                                            DDDDPPPPLLLLAAAACCCCEEEE((((5555))))
  71.  
  72.  
  73.  
  74.      A legal statement could be:
  75.  
  76.      mmmmeeeemmmmoooorrrriiiieeeessss (((( $$$$MMMMPPPP____SSSSEEEETTTT____NNNNUUUUMMMMTTTTHHHHRRRREEEEAAAADDDDSSSS ++++ 1111))))////2222 iiiinnnn ccccuuuubbbbeeee
  77.  
  78.      The first example can be written in a scalable fashion as follows:
  79.  
  80.      #### ssssccccaaaallllaaaabbbblllleeee ppppllllaaaacccceeeemmmmeeeennnntttt ssssppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn ffffiiiilllleeee
  81.  
  82.      #### sssseeeetttt uuuupppp mmmmeeeemmmmoooorrrriiiieeeessss wwwwhhhhiiiicccchhhh aaaarrrreeee cccclllloooosssseeee
  83.      mmmmeeeemmmmoooorrrriiiieeeessss $$$$MMMMPPPP____SSSSEEEETTTT____NNNNUUUUMMMMTTTTHHHHRRRREEEEAAAADDDDSSSS iiiinnnn ttttooooppppoooollllooooggggyyyy ccccuuuubbbbeeee
  84.  
  85.      #### sssseeeetttt uuuupppp tttthhhhrrrreeeeaaaaddddssss
  86.      tttthhhhrrrreeeeaaaaddddssss  $$$$MMMMPPPP____SSSSEEEETTTT____NNNNUUUUMMMMTTTTHHHHRRRREEEEAAAADDDDSSSS
  87.  
  88.      #### rrrruuuunnnn rrrreeeevvvveeeerrrrsssseeeedddd tttthhhhrrrreeeeaaaaddddssss aaaaccccrrrroooossssssss tttthhhheeee mmmmeeeemmmmoooorrrriiiieeeessss
  89.  
  90.      ddddiiiissssttttrrrriiiibbbbuuuutttteeee tttthhhhrrrreeeeaaaaddddssss $$$$MMMMPPPP____SSSSEEEETTTT____NNNNUUUUMMMMTTTTHHHHRRRREEEEAAAADDDDSSSS----1111::::0000::::----1111 aaaaccccrrrroooossssssss mmmmeeeemmmmoooorrrriiiieeeessss
  91.  
  92.      #### sssseeeetttt tttthhhheeee ppppaaaaggggeeee ppppllllaaaacccceeeemmmmeeeennnntttt ppppoooolllliiiiccccyyyy ttttoooo RRRRoooouuuunnnnddddRRRRoooobbbbiiiinnnn ffffoooorrrr ddddaaaattttaaaa ppppaaaaggggeeeessss
  93.  
  94.      ppppoooolllliiiiccccyyyy ddddaaaattttaaaa ppppllllaaaacccceeeemmmmeeeennnntttt """"PPPPllllaaaacccceeeemmmmeeeennnnttttRRRRoooouuuunnnnddddRRRRoooobbbbiiiinnnn""""
  95.  
  96.  
  97.      Static specifications may occur in a placement file or be called later
  98.      from ddddppppllllaaaacccceeee(3) library routines. Dynamic specifications may only be
  99.      called from ddddppppllllaaaacccceeee(3) library routines.  Here is a summary of the
  100.      grammar.
  101.  
  102.      Static specifications:
  103.  
  104.      mmmmeeeemmmmoooorrrriiiieeeessss _m [[iiiinnnn] [ttttooooppppoooollllooooggggyyyy] ccccuuuubbbbeeee|nnnnoooonnnneeee|pppphhhhyyyyssssiiiiccccaaaallll|ccccppppuuuucccclllluuuusssstttteeeerrrr] [nnnneeeeaaaarrrr
  105.      [/_h_w/*]+]
  106.  
  107.      tttthhhhrrrreeeeaaaaddddssss _n
  108.  
  109.      rrrruuuunnnn tttthhhhrrrreeeeaaaadddd _n oooonnnn mmmmeeeemmmmoooorrrryyyy _m [uuuussssiiiinnnngggg ccccppppuuuu _k]
  110.  
  111.      ddddiiiissssttttrrrriiiibbbbuuuutttteeee tttthhhhrrrreeeeaaaaddddssss [_t_0:_t_1[:_d_t]] aaaaccccrrrroooossssssss mmmmeeeemmmmoooorrrriiiieeeessss [_m_0:_m_1[:_d_m]] [bbbblllloooocccckkkk
  112.      [_m]]|[ccccyyyycccclllliiiicccc [_n]]
  113.  
  114.      ppppllllaaaacccceeee rrrraaaannnnggggeeee _k ttttoooo _l oooonnnn mmmmeeeemmmmoooorrrryyyy _m [[wwwwiiiitttthhhh] ppppaaaaggggeeeessssiiiizzzzeeee _n [kkkk|KKKK|mmmm|MMMM] ]
  115.  
  116.      ppppoooolllliiiiccccyyyy ssssttttaaaacccckkkk|ddddaaaattttaaaa|tttteeeexxxxtttt ppppaaaaggggeeeessssiiiizzzzeeee _n [kkkk|KKKK|mmmm|MMMM]
  117.  
  118.      ppppoooolllliiiiccccyyyy ssssttttaaaacccckkkk|ddddaaaattttaaaa|tttteeeexxxxtttt ppppaaaaggggeeeewwwwaaaaiiiitttt [ooooffffffff|oooonnnn]
  119.  
  120.      ppppoooolllliiiiccccyyyy ssssttttaaaacccckkkk|ddddaaaattttaaaa|tttteeeexxxxtttt ppppllllaaaacccceeeemmmmeeeennnntttt _s
  121.  
  122.      ppppoooolllliiiiccccyyyy mmmmiiiiggggrrrraaaattttiiiioooonnnn _n [%%%%]
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDPPPPLLLLAAAACCCCEEEE((((5555))))                                                            DDDDPPPPLLLLAAAACCCCEEEE((((5555))))
  137.  
  138.  
  139.  
  140.      mmmmooooddddeeee vvvveeeerrrrbbbboooosssseeee [oooonnnn|ooooffffffff|ttttoooogggggggglllleeee]
  141.  
  142.      mmmmooooddddeeee ssssiiiiggggnnnnaaaallll eeeexxxxpppprrrr
  143.  
  144.      Dynamic specifications:
  145.  
  146.  
  147.      mmmmiiiiggggrrrraaaatttteeee rrrraaaannnnggggeeee _k ttttoooo _l ttttoooo mmmmeeeemmmmoooorrrryyyy _m
  148.  
  149.      mmmmoooovvvveeee tttthhhhrrrreeeeaaaadddd|ppppiiiidddd _n ttttoooo mmmmeeeemmmmoooorrrryyyy _m
  150.  
  151.      In the above, the specification: tttthhhhrrrreeeeaaaaddddssss  _t_0:_t_1[:_d_t] means to use threads
  152.      numbered _t_0 through _t_1 with an optional stride of _d_t. The default stride
  153.      value is 1.
  154.  
  155.      Similarly, the specification: mmmmeeeemmmmoooorrrriiiieeeessss [_m_0:_m_1[:_d_m]] means to use memories
  156.      _m_0 through _m_1 with an optional stride of _d_m. The default stride value is
  157.      1.
  158.  
  159.      The qualifier bbbblllloooocccckkkk _m implies a block distribution of the threads with at
  160.      most _m threads per memory. If  _m is omitted, its default value is: the
  161.      integer ceiling of the number of threads being distributed divided by the
  162.      number of memories being distributed across.
  163.  
  164.      The qualifier ccccyyyycccclllliiiicccc _n implies a cyclic distribution of the selected
  165.      threads across the selected memories. The threads are chosen in groups of
  166.      _n and dealt out to the appropriate memory until all threads are used. If
  167.      _n is omitted, its default value is one and the threads are dealt out to
  168.      the memories like a deck of cards.
  169.  
  170.  
  171. EEEERRRRRRRROOOORRRR HHHHAAAANNNNDDDDLLLLIIIINNNNGGGG
  172.      If errors are encountered in the _p_l_a_c_e_m_e_n_t__f_i_l_e, the default procedure
  173.      for ddddppppllllaaaacccceeee is to print a diagnostic message to standard error specifying
  174.      where the error occurred in the _p_l_a_c_e_m_e_n_t__f_i_l_e and abort execution.  If
  175.      errors are encountered in the libdplace.so library during the run-time
  176.      execution of _p_r_o_g_r_a_m, then a diagnostic message is sent to standard
  177.      error, a default signal of SIGKILL is sent to all members of the process
  178.      group, and execution is aborted.
  179.  
  180.      The mmmmooooddddeeee ssssiiiiggggnnnnaaaallll eeeexxxxpppprrrr statement allows a selection of a specific signal
  181.      number to be generated upon error.  If the mmmmooooddddeeee ssssiiiiggggnnnnaaaallll eeeexxxxpppprrrr is specified,
  182.      the action taken when libdplace.so detects a run-time error is to send
  183.      the signal number derived from eeeexxxxpppprrrr to the _p_r_o_g_r_a_m invoked by ddddppppllllaaaacccceeee.
  184.      Under this condition the control is returned to the caller, which is the
  185.      _p_r_o_g_r_a_m.  The signal number can range from 1 to 32.
  186.  
  187.      An example of how to set the signal number:
  188.  
  189.      mmmmooooddddeeee ssssiiiiggggnnnnaaaallll 11116666
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDPPPPLLLLAAAACCCCEEEE((((5555))))                                                            DDDDPPPPLLLLAAAACCCCEEEE((((5555))))
  203.  
  204.  
  205.  
  206.      Upon detecting an error in libdplace.so during run-time, signal 16
  207.      (defined as SIGUSR1) is sent to the calling process (in this case the
  208.      _p_r_o_g_r_a_m and control is returned to the caller.
  209.  
  210.  
  211. CCCCOOOOMMMMMMMMOOOONNNN PPPPLLLLAAAACCCCEEEEMMMMEEEENNNNTTTT FFFFIIIILLLLEEEE EEEERRRRRRRROOOORRRRSSSS
  212.      The most common placement file error is the use of either the rrrruuuunnnn or
  213.      ddddiiiissssttttrrrriiiibbbbuuuutttteeee directive without previously declaring both the number of
  214.      threads, and the number of memories using the mmmmeeeemmmmoooorrrriiiieeeessss and tttthhhhrrrreeeeaaaaddddssss
  215.      directives.
  216.  
  217.  
  218. TTTTEEEERRRRMMMMIIIINNNNOOOOLLLLOOOOGGGGYYYY
  219.      In the above, a tttthhhhrrrreeeeaaaadddd is an IRIX process or any of its descendants which
  220.      were created using sssspppprrrroooocccc(2) or ffffoooorrrrkkkk(2). Thread numbers are ordered (from
  221.      0 to the number of threads minus 1 ) in the same way as the pid's for
  222.      each process.
  223.  
  224.      A mmmmeeeemmmmoooorrrryyyy is an instantiation of a physical memory.
  225.  
  226.      A rrrraaaannnnggggeeee is a virtual address range such as 0x100000 to 0x200000.
  227.  
  228.  
  229. PPPPLLLLAAAACCCCEEEEMMMMEEEENNNNTTTT PPPPOOOOLLLLIIIICCCCIIIIEEEESSSS
  230.      The placement policies are specified according to mmmmmmmmcccciiii((((5555)))). The current
  231.      valid policies are PPPPllllaaaacccceeeemmmmeeeennnnttttDDDDeeeeffffaaaauuuulllltttt, PPPPllllaaaacccceeeemmmmeeeennnnttttFFFFiiiixxxxeeeedddd, PPPPllllaaaacccceeeemmmmeeeennnnttttFFFFiiiirrrrssssttttTTTToooouuuucccchhhh,
  232.      PPPPllllaaaacccceeeemmmmeeeennnnttttRRRRoooouuuunnnnddddRRRRoooobbbbiiiinnnn, PPPPllllaaaacccceeeemmmmeeeennnnttttTTTThhhhrrrreeeeaaaaddddLLLLooooccccaaaallll, PPPPllllaaaacccceeeemmmmeeeennnnttttCCCCaaaacccchhhheeeeCCCCoooolllloooorrrr.
  233.  
  234.  
  235. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  236.      ddddppppllllaaaacccceeee(1), ddddpppprrrrooooffff(1), ddddppppllllaaaacccceeee(3), nnnnuuuummmmaaaa(5), mmmmmmmmcccciiii(5), hhhhwwwwggggrrrraaaapppphhhh(4)
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.